Appendix F - Task Listing Sorted Alphabetically 70
Appendix G - Global Variables & Constants 76
Initialized In The Initglobals Task 76
Controlling The Test Level 85
Initialized In The Initdraw Task 87
Initialized In The Initfonts Task 91
Initialized In The Initrandomseed Task 94
Undefined Task References - Hooks 95
Appendix H - Test Cases in SPEC S&L 99
Appendix I - Utility Tools 101
MouseTrap 101
vuCollect 101
MiniLauncher 101
OnTarget 101
Acknowledgments
This document is the result of fruitful work from several individuals that deserve to be mentioned, even though some of them have moved on to other challenges at Apple and are no longer working closely with us. We want to thank them for the excellent effort, support and cooperation:
Key Contributor:
Dave Matzner, Michael Leong, Gil Spencer, Ken Landreth, Jeff Mitchell, Nick Vaccaro, Eric Hewitt.
Other Contributors:
John Coelho, Mikel De Sanctis, Jay Jessen, John Harrison, Kristi Kokalis, Naga, Stuart Russell, Nancy Schorr, Carol Wilser and the entire Virtual User team.
About This Document
SPEC S&L is a collection of Virtual User scripts and libraries developed to expedite the Macintosh application and system software compatibility test process. This document is a user's guide for people who intend to utilize SPEC S&L. The document is divided into two parts. Part I addresses the execution of scripts, intended for individuals running scripts within the SPEC S&L framework. We have attempted to include many of the issues that can arise when setting up and running an automated test lab. Part II describes the SPEC S&L libraries in specific detail, intended primarily for individuals developing new scripts and libraries within the SPEC S&L framework. This document will evolve over time, to address most of the issues that arise as people begin using SPEC S&L.
Introduction
Automation Overview
Virtual User is a user-level automation system designed for the purpose of testing the elements of the Macintosh human interface. If you are not familiar with Virtual User you may want to read Setting Up and Running Virtual User and/or Virtual User Language Reference Guide. By utilizing Virtual User to automatically exercise features of the human interface, test suites can be developed that will verify various levels of functionality. Test suites once developed will provide numerous benefits. Below is a list of some of the benefits provided by the use of automation.
Benefits:
- Reusable test suites
- Repeatable test execution
- Multiple configurations tested concurrently
- Automate tedious tasks
- Benchmark performance
- Integration with environmental variables
S&L Overview
SPEC S&L is a collection of Virtual User (VU) libraries and scripts that will help quality engineers verify compatibility with third party products. Automated testing utilizing Virtual User has provided a means for limiting the amount of resources required to verify software compatibility with third party products. SPEC S&L addresses the need to have a single framework for developing Virtual User automated test scripts. SPEC S&L will help software engineers by performing the repetitive tasks involved in verifying compatibility in two ways:
1) Providing a collection of compatibility tests for many of the major third party applications existing for the Macintosh.
2) Providing an extendible script development framework for groups that are interested in automating additional compatibility testing.
SPEC S&L contains two distinct elements: Scripts and Libraries. Libraries are a collection of commonly used tasks. By placing commonly used tasks into libraries we gain several advantages:
1) Reusable VU code base.
2) Smaller more efficient scripts.
3) Consistency - Testing common features between applications in similar manner.
4) Maintainability - Handle changes in central location instead of updating numerous files.
5) Flexibility - Ability to override default routines, if application features require it.
6) Extendibility - It is easy to extend any of the data structures in the libraries to handle additional features, and since everything that is specific to an application is contained within one script file it is easy to add additional features to the test suite without affecting other suites.
SPEC S&L scripts are made up of several elements including: calls to library tasks, application specific data structures, application specific tasks. By limiting what the scripts contain, we have set a standard for limiting code redundancy. Since the majority of the testing is controlled from the same set of libraries, testing between applications is very consistent. The application data structures mentioned above are discussed in Part II of this document. For more information on Scripts refer to the section titled QuickLook Scripting.
Important Notes
- Some applications require serial numbers, or have a copy protection mechanism to prevent multiple copies running simultaneously. When executing scripts for those application for more than one target, only the first copy of the application will be able to launch, all the others will get an error. The scripts for those applications are: 4D.vu, Canvas.vu, Mathematica.vu, and QuarkXpress.vu, PhotoShop.vu and Director.vu.
Part I – Execution
Setup & Execution
The initial setup required to run a Virtual User automation suite can vary depending on the specifics of the test suite. This section describes the setup required to use SPEC S&L. The following instructions assume that VU is installed according to the guidelines presented in 'Setting Up and Running Virtual User'.
Target Setup
1) Install all applications to be tested on target hard drive. See section titled "The Cloning Process" for more information.
2) Install the 'Agent VU' Extension.
3) Name each target in the 'Machine Name' field of the 'Sharing Setup' CDEV.
• This is done so that the target can be identified on the net.
• It is necessary to reboot all targets after naming so that they can be registered on the network.
4) Set the Key Repeat Rate to OFF in the 'Keyboard' CDEV.
• This is done so that typing will be accurate, and letters will not be unexpectedly repeated (This will cause error with our launching scheme).
5) Select a printer driver in the 'Chooser'.
• This is done because many applications require a printer to be selected prior to opening a new document.
6) Insure that a copy of the VU external tool, OnTarget in located on all target machines.
• OnTarget is used to preflight all targets to insure that scripts can run on a given configuration (see gLaunchReqs).
• To access OnTarget (or any other external tool) you must select the Sharing Setup CDEV and turn on Program Linking.
• To allow guest access: Open the Users & Groups CDEV, double-click on the <Guest> icon, and select the check box titled 'Allow guests to link to programs on this Macintosh' (see Host Setup for detail concerning AutoGuest).
7) Configure each target's system environment.
• All software/hardware configurable system variables should be set prior to executing a test suite. For instance: if your test suite requires that the test be run in 32 bit addressing mode, it is important to place the machine in this state (either manually or automatically - by way of script) prior to executing the test.
• Ensure the first element of the Scrapbook contains text. This can be accomplished by using any word processor to type the desired text and paste it onto the Scrapbook.
8) Launching Setup
• In order for the libraries to launch the intended application each of the application scripts references a global variable in the Globals.lib titled gAliasDirectory. This global variable is the name of a directory (or alias to a directory) in the Apple Menu, which contains the applications (or application aliases).
To use the existing system:
1) Create and name a folder on the target hard disk: for example: '#Aliases''. This is the default name that is assigned to the global AliasDirectory.
2) Place an alias to this folder in the 'Apple Menu Items' folder.
3) Place aliases to all applications in the '#Aliases' folder.
Note: The '#' sign precedes the name 'Aliases' so that it will be at the top of the Apple Menu, which is sorted alphabetically.
An alternative method is to place the application (or its alias) in the Apple Menu directly.
Host
SPEC S&L requires Virtual User 2.0x, but does not require any unique setup for the host machine except for installing the AutoGuest extension (see below), and allocating enough memory to the Virtual User application via the Get Info box. When using SPEC S&L, 4 MB or more is recommended for V.U. Please refer to Setting Up and Running Virtual User and/or Virtual User Language Reference Guide.
1) Install the AutoGuest Init
• This is done so that the host will be able to automatically log onto all targets when making calls to external tools. AutoGuest allows guest access Program Linking to occur without any confirmation dialogs.
The Cloning Process
Keeping current versions of third party software on all target machines is critical to maintaining compatibility information. Cloning hard drives is a method used to update numerous target hard drives concurrently. The cloning process entails establishing a single hard drive, the 'Clone Master' with the latest version of each application to be tested. The Clone Master then needs to be copied to each of the target CPU's.
The section that follows details the steps to be taken when setting up the Clone Master and cloning it:
1) Copy all of the applications (and appropriate files) to be tested to the Clone Master hard drive.
Note: Normally only files which are required are copied to the Clone Master. Generally there are a lot of extraneous files in product packages, these files can usually be removed to free disk space.
We have distinguished four types of files:
- Files which are required for the application to launch
- Files which are not required but test system functionality
- Files which are not required and therefore extraneous
- Sample documents
2) After Clone Master has been updated, aliases to each of the applications need to be created. Place all aliases in a single folder (#Aliases), these will be used to launch the applications.
Note: Remember that the state of the Clone Master will directly effect the state of all hard drives cloned from it. Make sure that everything is set up the way you intend, otherwise a long and tedious process of manually updating all target drives may be necessary. The best way to test that your Clone Master is set up properly is to run a full series of scripts against the Clone Master. This will insure that all of the required files are available for each application.
1) Double-click each alias to make sure the application launches.
Note: If an alias is made on the Clone Master the alias will not work on a drive that was directly copied from the Clone Master unless it is named the same.
2) If an application has a special registration screen, such as Name, Password, etc. enter in the information necessary to dismiss this screen. (Applications that require unique serial numbers are a royal pain in the neck)
3) Check to insure that all required tools exist.
- Macsbug, and Debugger Prefs, Agent VU, Programmer's Key, ResEdit, etc.
4) Check to insure all required files exist.
- Sample Files
- Files needed for script execution, e.g. If Spell Checking is tested, is a dictionary present.
- Files necessary for launching.
3) The final step of the clone process is to copy Clone Master to each target drive. There are two methods we normally use for cloning and/or updating drive(s).
A) Finder Copy -
1) Mount the Clone Master and the drive to be cloned.
2) Erased/ Reformat the drive to be cloned.
3) Select all the files on the Clone Master and drag them to the drive to be cloned.
Note: The names should be the same in order for the aliases to be resolved.
B) GraceLAN - Update Manager tool.
Part II – Development
Scripts Overview
The scripts provided in this product are meant to serve as examples of developing tests based on the included libraries. All the scripts fall under the category of QuickLook test. The term QuickLook is used to define a set of tests that exercise a limited set of features of a given software product. In the context of SPEC S&L, the term QuickLook refers to a script that tests a limited set of features of a given third party application. The features that are tested in a QuickLook are generally features that are common between applications, such as: saving/opening files, resizing and closing windows, etc. For specific details concerning the features exercised within a QuickLook please refer to Appendix A: QuickLook definition. In this section we will be discussing the various elements that make up an application QuickLook script in detail.
The Elements That Make Up A Quicklook
This section describes guidelines concerning various elements within the standard SPEC S&L QuickLook script. Please refer to Appendix A: Standard QuickLook Definition for information concerning the features tested in a QuickLook and Appendix B: Sample QuickLook for specific examples concerning QuickLook implementation.
There are five basic elements that make up a standard SPEC S&L script.
1) Descriptive Header
2) Library Declarations
3) Application Specific Task Definitions
4) Script Declaration
5) Body Of The Script
In the following section we examine each of these elements in detail.
Descriptive Header
The descriptive header is used to provide basic information and a change history for the script. Below is a sample script header, the information contained within it should be self-explanatory.
Library declarations are necessary whenever a script makes a call to a task that is contained with in a library. For more information concerning tasks that are contained within each specific library please refer to Appendix E: Tasks within Libraries. The following example shows a sample library declaration. Note: The following sample library declaration contains the minimum libraries that are necessary for developing a Standard QuickLook.
The application specific tasks section of a script is the section that provides the script writer with the most flexibility. This section is where the script writer should define any application specific data structures, tasks used for task overrides, as well as any additional application specific tasks. For examples on what is expected in the application specific tasks section please refer to either Appendix B: Sample QuickLook or any of the SPEC S&L scripts.
Script Declaration
The script declaration indicates the beginning of the body of the script. It begins with the word “Script” followed by the script's title, which in terms is followed by the script parameter(s). For example:
# Script Definition
Script Sample (Param1, Param2...)
Scripts written for SPEC libraries take advantage of the script parameter feature in V.U. to control the depth of testing to perform. Utilizing this technique, the script writer can provide flexibility to perform different complexity of tests by letting the person executing the script change the script parameters at run time. There are two ways to change the script parameters, using Virtual User's Setup menu or using a controller script to redefine the parameter.
The convention used for SPEC compliant scripts is one script parameter. For example:
script MacDrawPro (ScriptLevel := -1)
For more information see Controlling the Test Level section in Appendix G.
Body Of A Script
The body of the script is where the calls to individual tasks are made. The body of the SPEC S&L scripts begins with global definitions and initialization. After this, the next step is to launch the application to be tested.
Within the body of each QuickLook script there are five basic areas of functionality that are normally present.
1) Application setup - DoSetUpApp()
2) Exercise drawing tools - DoDraw()
3) Exercise text entry by changing fonts, sizes and styles - DoText()
4) Exercise windows - DoWindow()
5) Application completion routines - DoCloseApp()
1) Application Setup
The standard SPEC S&L QuickLook definition requires that certain specific test cases are executed. Many applications handle these test cases in different ways, and some do not support them at all. There are a couple of high level miscellaneous tasks that were developed to handle a variety of application idiosyncrasies. For example, some applications display a default document window automatically when launched, others do not. The following is an example of the convention used to describe task definitions. For more details, see the heading “Conventions Used for Tasks Definitions” under the Library Overview section.
return value TaskName( parameter1, parameter2,...)
DoSetUpApp() is a high level task that calls the appropriate low-level tasks necessary to generate predefined QuickLook test cases. The parameters to DoSetUpApp() allow the script writer to specify the way to handle several application specific test cases including: Dismissing a dialog that appears after launching, define what is the default window specifier, the menu items required for selecting a new document, dismissing any dialogs that appear when creating a new document, whether or not the application supports text and/or PICT copied from the scrapbook, And whether or not to save the document. For more information see the task header of DoSetUpApp() in the DoTasks.lib.
Examples:
• DoSetUpApp(1,0,{"New","File"},1,1,1,1);
# After launching it will dismiss the dialog that appears, the document window is the first window that has a zoom and a close box, select the 'New' menu item from the 'File' menu, dismiss the dialog that appears, copy and paste text from the scrapbook, copy and paste a PICT from the scrapbook, and save the file.
# After launching there shouldn't be a dialog that appears, select the 'New File' menu item from the 'Document' menu, the document window is ordinality 1 but not the first one with a zoom and close box, no dialog should appear after selecting 'New File', it will not copy and paste text or a PICT from the scrapbook, and it will not save the file.
2) Exercise Drawing Tools - (see Performing Draw Operations)
Note: using MouseTrapper may greatly enhance your ability to define the Draw structures.
DoCloseUpApp() is a high level task that calls the appropriate low-level tasks necessary to generate predefined QuickLook test cases. The parameters to DoCloseApp() allow the script writer to specify the way to handle several application specific test cases including: Save a document, modify it and then revert to the last save version, Whether or not it is possible to display the about box and dismiss it, whether or not to test Page Setup and/or Print. For more information See the task header of DoCloseApp() in the DoTasks.lib.
Examples:
• DoCloseApp(1,1,1,1,1);
# Save a document, modify it and then revert to the last saved version, then select the 'About' menuItem, and click in the center of the screen once to dismiss it, and do whatever Page Setup and Printer tests were defined.
Scripts Included With This Package
SPEC S&L includes over 20 Virtual User scripts written using the techniques previously mentioned. They exercise some of the most popular Macintosh applications and are a good source of examples. See Appendix C for a complete list of the SPEC S&L scripts.
Libraries Overview
Many of our libraries rely on routines that are contained in separate library files. We have attempted to limit dependencies where possible. However, in order to organize them logically, retaining modularity, certain dependencies were necessary. The layer model discussed in a later section (SPEC S&L Layer Model) simplifies the dependencies See Appendix D for a list of the library dependencies.
How To Use The Libraries
The SPEC S&L libraries are provided so that you can build your custom libraries and test scripts based on the tasks in them. The libraries have tasks that are published for use and some supporting tasks that are not meant for use by you. These unpublished tasks may change in future and/or will not be supported. They are there to make the other published tasks work.
You can use any of the published tasks in the SPEC S&L libraries. The published tasks are marked (accessible from the Mark menu in MPW). We follow the convention of defining published tasks using the uppercase word TASK. For example:
is a task that is published for you to use from your custom libraries and scripts. Do NOT edit any of the files in the SPEC S&L package. All the text files are provided to you with the read-only flag set. If you have a need to enhance any particular library, consider the options given later in this section.
Library Task Benefits
Many of the tasks in the lower layer libraries, (see SPEC S&L Layer Model), like UserInterface.Lib, have parallel functions provided in the Virtual User scripting language. The benefit of calling the tasks in the libraries, as opposed to making Virtual User primitive calls, is that the tasks in the libraries perform error checking, log results and return result values. For example:
• The library call:
SelectButton("OK");
• Replaces the VU primitive call:
Select[button t:'OK'];
The call to the library will:
Check - to see if the button exists and is enabled.
Log - Selected button titled 'OK'.
Return - the name of the button that was selected.
Note: The libraries make Virtual User primitive calls
Adding To / Modifying The Libraries
Before you decide to add to, or modify the libraries, consider all your options.
Hooks:
This package provides a number of undefined task references (hooks) for convenience when customizing your tests. Refer to the section, "Hooks Provided in SPEC S&L" in Appendix G, for more information.
Redefine Default Values:
Use Custom.Lib to redefine global variables via the task InitCustom(). InitCustom() is called by InitGlobals() after all globals have been defined. Using this method does not require altering any other library in the package.
Add functionality:
Build a library of your own that has tasks with new names that act as wrappers around the tasks in the library from the SPEC S&L package. Now you can add any enhancements to this customized library.
Modify Tasks:
Copy the task to be modified into your script or custom library, rename the task to something different and make the changes you want. From now on you have disassociated this task from the one in SPEC S&L package. This helps in two ways: first, in a future version of SPEC S&L if this task is modified your version of the task will not be adversely affected; second, you can still use the original task for other purposes where the modification is not required.
Fixing A Bug In The Libraries
This is something we would like you not to face. But if you do discover a bug in the SPEC S&L, first report the problem to us using RADAR. If you need a fix immediately and cannot wait for the next release of SPEC S&L, then please adopt the approach mentioned above for modifying SPEC S&L until a fix is made available.
Conventions Used For Task Definitions
The tasks defined in these libraries follow the convention indicated below in italic text:
return value TaskName( parameter1, parameter2,...)
return value can be any VU valid type or nada (none), always listed on the left margin
TaskName always indicated in bold/italicized text
( parameter1, parameter2,...) parameters separated by commas
All the parameters inside a task definition begin with the letter “p”. For more information about particular parameters, default values, etc. see the task header inside the library.
SPEC S&L Layer Model
SPEC S&L is intended to provide an insight into, and a solution for, some of the many issues that arise in developing an automation process. SPEC S&L's libraries are a compilation of tasks (procedures) that provide a variety of functions. They have been organized into layers based upon function. Libraries in lower numbered layers do not depend on any library in higher numbered layer.
Layer I • Fundamental data structures and then manipulation
• Output formatting and redirection
• Shared Global variable initializations
Custom.Lib
Geometry.Lib
Globals.Lib
OutPut.Lib
String.Lib
Utility.Lib
Layer II • External tool specifications and supporting tasks
FileTool.Lib
OnTarget.Lib
MathTool.vulib
Layer III • Basic user interactions on the target
Gestalt.Lib
Palette.Lib
StandardFile.Lib
TCS.Lib
UserInterface.Lib
Layer IV • High-level task oriented user interactions on the target
Draw.Lib
Font.Lib
LaunchQuit.Lib
Print.Lib
Select.Lib
TargetCheck.Lib
Text.Lib
Layer V • General support for using libraries on the lower layers
DoTask.Lib
Layer VI • Application specific tests
DA.Lib
WordProcessor.Lib
Exercising Window Features
Overview
SPEC S&L contains a collection of several tasks which support exercising the many standard window features, including: closing, zooming, resizing, scrolling, etc. This section describes the routines support testing window functionality.
Specifier is a parameter used throughout the window tasks. This parameter refers to a window specifier and can be one of three types. It is possible to specify a window by name by passing in the name of the window as a string, e.g. ZoomWindow('Untitled').
It is also possible to specify a window by ordinality by passing in an integer, e.g. ZoomWindow(1). If a more complete window descriptor is required it is possible to pass any partial or complete window descriptor, e.g. ZoomWindow([window t: 'Untitled' c: true s:Dialog]). If a specifier is set to 0 then actions will take place on the front document window, e.g. ZoomWindow(0). We have defined the front document window as the front most window that contains a closebox and a growbox. If your applications front document window does not contain a closebox and a growbox then you will be required to pass in the proper specifier.
DoWindow() is a high level task that calls the appropriate low-level tasks necessary to perform predefined window test cases. There are several different test methods available for DoWindow() these are discussed in detail below. It is possible to use the global gWindowMethod to set the test method, only if no parameters are passed to DoWindow(). This is because parameters take precedence over gWindowMethod .
Note: DoWindow() is the only task within the window routines not contained in UserInterface.Lib, it is contained in DoTasks.Lib. If some of the tests performed by a particular TestMethod in DoWindows() are not available for a specific application it is possible to define which tests are available by setting the appropriate flags in the global gDoWindowList.
Examples:
• DoWindow(0); # Nothing - DoWindow() will not execute.
• DoWindow(1); # Completed set of window tests
• DoWindow(2); # QuickLook set of window tests
• DoWindow({1,3,5,7,9}); # Pass in a set of window tests
Performs the specified functions as defined in the input parameter pFunctionList. If pFunctionList is not passed, or is passed as 0, then the following operations are performed on the window specified by input parameter pSpecifier. The default behavior will perform the following behaviors on the front most document window.
Listed below is the list of function numbers and a brief description of what that particular function does:
0 Complete Window Test - Performs functions 1 through 17
(17 is done twice - zoom & zoom back)
1 Resize to random width and height.
2 Attempt resize to 20,20 (should not allow it)
3 Scroll the vertical scroll bar to random location.
4 Scroll the vertical scroll bar to end location.
5 Scroll the vertical scroll bar to beginning location.
6 Scroll the vertical scroll bar to original location.
7 Scroll the horizontal scroll bar to random location.
8 Scroll the horizontal scroll bar to end location.
9 Scroll the horizontal scroll bar to beginning location.
10 Scroll the horizontal scroll bar to original location.
11 Resize window to largest possible and then
12 Resize back to smallest window size
13 Size window across screen border to second screen (if 2 screens) and back.
14 Drag window across screen border and back
15 Drag random location and back to original location
Note: This is the same as 19 except it sizes the window to the smallest possible size. This is better in that it is more likely for the scrollbars to be active.
23 A More Complete Window Drag Test
Performs functions 2, 14, 15, and 16
Note: This is the same as 20 except it sizes the window to the smallest possible size. This is better in that it is more likely for the window to be able to be dragged across screen boundaries.Examples:
• TestWindow(); # Complete window test on frontmost document window
• TestWindow(1, 12);
# Drag the frontmost window across the screen border and back.
• TestWindow(0, {1,2,3,5}, 1,2);
# Perform tests 1,2,3,5 on the frontmost document window twice, restores the window to its original condition when done.
integer DragAcrossScreens( pSpecifier, pDragXY )
This task provides a mechanism to drag a window across multiple monitors. In order to drag a window across multiple monitors the target machine must be configured with multiple monitors. This task will verify that multiple monitors are available, if they are not nothing will be done, and the appropriate return values will be returned.
Examples:
• DragAcrossScreens(0);
# Drag the frontmost document window across multiple monitors if they are present.
integer SizeAcrossScreens( pSpecifier, pDragXY )
This task provides a mechanism to size a window across multiple monitors. In order to size a window across multiple monitors the target machine must be configured with multiple monitors. This task will verify that multiple monitors are available, if they are not nothing will be done, and the appropriate return values will be returned.
Examples:
• SizeAcrossScreens(0);
# Size the frontmost document window across multiple monitors if they are present.
This task provides a mechanism to close specified windows. There are three possible ways to close a window, closebox, close menu item, and keyboard equivalent. Using the first input parameter, pHowClose, it is possible to specify the method desired to close the window. If changes to a document are made prior to closing, a dialog appears asking whether to save the changes or not, the saveFlag parameter enables you to specify whether or not you want to save the document, and the newDocName allows you to specify what to name the document if it hasn't been saved before.
Examples:
• CloseWindow();
# Close the frontmost document window by selecting the close box, will save the document if needed.
• CloseWindow(2,0,1);
# Close the frontmost window by way of a keyboard equivalent, will not save the document.
• CloseWindow(1,1,0,"myDoc")
# Close the frontmost document window by selecting the 'Close' menu item, will save the document if needed with he name 'myDoc'.
This task provides a mechanism to scroll windows using either the vertical or the horizontal scrollbars.
Examples:
• ScrollWindow('H',1,2);
# Scroll the document windows horizontal scrollbar to the position 1/2.
• ScrollWindow("V", 0,1);
# Scroll the document windows vertical scrollbar to the topmost position.
Performing Standard File Operations
Overview
SPEC S&L contains a collection of tasks which support many of the features of Standard File, including: saving files, opening files, navigating directories, etc. This section describes the routines that make up StandardFile.Lib.
Most of the tasks that support Standard File allow the script writer to pass parameters into tasks to perform a specific operation. For example, SaveAs() takes a file name as a parameter allowing the scriptwriter to specify the name of the file to be saved. There is one very high level task, DoFiles(), that automatically tests several features of StandardFile. For example, DoFiles(2) will: Save a file (if a document with the same name already exists it will be replaced), close the file, reopen the file.
The Standard File library tasks will only work with System 7.0 or greater. The reason for this is because of the way in which navigation and selection of files occurs within the Standard File support tasks. Files and folders are selected by what is referred to as "Type Selecting". "Type Selecting" means selecting the desired item by typing its name. While this is effective when the desired files and folders exist, it can cause problems when they do not. While we have done some error checking to help insure that the expected behavior is actually occurring, proper set up of the target machines can greatly enhance the probability of success. NOTE: Since we use "Type Selecting" it is possible that only specifying the first couple of letters of each path element will actually navigate correctly, for example, The path {"myHardDisk", "Folder1", "myDocuments"} could possibly have been specified as {"myH", "Fol", "myDoc"}. Please use caution when using this method, since it is far less descriptive of what the desired result should be.
DoFiles() is a high level task that calls the appropriate low-level tasks necessary to generate predefined Standard File test cases. There are several different test methods available in DoFiles, These are discussed in detail below. It is possible to use the global gFileMethod to set the test method, only if no parameters are passed to DoFiles(). This is because parameters take precedence over gFileMethod.
Note: DoSetUpApp, and DoCloseApp() make specific calls to DoFiles() within the Standard SPEC S&L QuickLook framework. Dofiles is the only task within the Standard File libraries not contained in StandardFile.Lib. It is contained in DoTasks.Lib.
Examples:
• DoFiles(0); # Does nothing - DoFiles() is turned OFF
• DoFiles(1); # All of the file tests below
• DoFiles(2); # Save a File, close it, reopen it.
• DoFiles(4);
# Select Save As, Cancel, Save with a unique name, Save As with the same filename (replace the existing one), Save as with the same name (add file name extension to generate a new file).
• DoFiles(5); # Select Save As, Cancel, select Save.
SaveAs() provides the ability to navigate through Standard File and save files. This routine allows the scriptwriter to specify whether or not to replace an existing file with the same name. The <Pathlist> parameter should be specified as a full pathlist, with the name of the drive as the first element.
Examples:
• SaveAs();
# Verifies a Standard File dialog is present, generates a filename based on the current application and the time of day, saves the file.
• SaveAs("myFile", 0);
# Will not select the 'Save As' menu item (but will verify that Standard File is present), name the file 'myFile', and if a file with the same name exists a new file name will be generated. The new file name is based on the existing filename appended with the time of day.
• SaveAs("myFile", 1, 1);
# Select the 'Save As' menu item, name the file 'myFile', and replace a file with the same name if one exists.
• SaveAs("myFile", 1, 0, {"HD", "Folder1"});
# Checks to verify that Standard file is already present, navigate to the specified path, name the file 'myFile', and replace a file with the same name if one exists.
OpenFile() provides the ability to navigate through Standard File and open files. The <Pathlist> parameter should be specified as a full pathlist, with the name of the drive as the first element. This is true unless the <PartialPath> flag is set indicating that navigation should begin from the current directory downward.
Examples:
• OpenFile("myFile");
# Selects the 'Open' menu item, types "myFile" to select the desired file, and presses the return key to open, then verifies that 'myFile' was opened properly.
• OpenFile("myFile", 2);
# Presses the keyboard equivalent Command-'o' to select the 'Open' menu item, types "myFile" to select the desired file, and presses the return key to open, then verifies that 'myFile' was opened properly.
• OpenFile("myFile",1,{"HD", "Folder1"});
# Selects the 'Open' menu item, selects the 'DeskTop' button and navigates the specified path, types "myFile" to select the desired file, and presses the return key to open, then verifies that 'myFile' was opened properly.
# Selects the 'Open' menu item, navigates the specified path, types "myFile" to select the desired file, and presses the return key to open, then verifies that 'myFile' was opened properly.
integer Revert( pRevertMI )
This task will attempt to revert the current document back to the last saved version by selecting any menu item that contains the word "Revert". It will then attempt to dismiss any confirmation dialog that appears. If RevertMI is defined as the menuItem for revert, it will be selected. Otherwise a menuItem with the word 'Revert' in it will be selected. A dialog will normally appear confirming the revert request. Several methods will be used when attempting to dismiss the dialog. Attempts to match buttons "OK", "Yes", "Revert", are made, then typing the return key. If RevertMi is defined, then DialogCheck() will be called to output the static text in the dialog and the type the return key.
Examples:
• Revert();
integer IsStandardFile( pLogIt )
This task checks to see if a Standard File dialog is present and returns 1 if it is present and 0 if it is not. All of the routines in the Standard Files Libraries call this task to determine if Standard File is present. Since it is possible to customize Standard File it is difficult to find a descriptor that will insure that Standard File is actually present.
This tasks selects cancel for the Standard File dialog. The main reason this is a task provided by Standard File library is that is a common test case for the SPEC S&L Standard QuickLook.
Examples:
• CancelStandardFile();
# Presses the keyboard equivalent Command-'.' to cancel
• CancelStandardFile(1); # Selects the 'Cancel' button
nada Save( pSaveMethod )
This task selects the 'Save' menu item. If a Standard File dialog appears, indicating the file has not been saved previously, the task SaveAs() is called. The main reason this is a task provided by Standard File library is that is a common test case for the SPEC S&L Standard QuickLooks.
Examples:
• Save();
Exercising Fonts
The 'Font.Lib' contains VU code for exercising fonts, styles, and sizes. There are three modes of font testing currently defined. These can be executed by calling DoText with certain global variables set appropriately. The following section details the proper global settings to execute the various test methods. All of the methods are based on the execution of a FontRecord which consists of three elements {"FontName", "SizeName", {StyleList}}; For example: ourFontRecord := {'Geneva','12',{'Bold','Italic'}};
Font Related Global Variables
In order to execute any of the font testing methods there are a series of global variables that must be defined in the task InitFonts().
NOTE: These global variables are actually used as constants. We have defined default settings for these global variables in Fonts.Lib. If the script that you are developing requires changes to the default values these should be made by overriding them within the script.
All font characteristics are generated from the predefined global font lists: gFontList, gFontSizeList, gFontStyleList. Define these lists with appropriate Fonts, Sizes and Styles. These are the first block of global variables in InitFonts().
DO NOT define the second block of global variables (gCurrFontMenu, gCurrSizeMenu, gCurrStyleMenu). These global variables will be automatically defined. They store the titles to the menus which contain the font characteristic menu items.
The global gPlainStyle should be defined as the menu item which clears all font styles.
The global gNextLineMethod should be defined as the appropriate method which a particular application requires to be prepared to enter the next line of text.
This global should be set to one of the following settings:
1 - ReturnKey
2 - Enter Key
3 - Down Arrow Key
4 - Tab Key
{<Optional Specifier>} - if no specifier will select the first document window with close and grow box.
See Appendix G for more info on gNextLineMethod
The global gNextLineClearsFontSettings should be set to a 1 if the method of moving to the next line of text clears all the font settings. It should be set to 0 if moving to the next line retains the font settings - ( important if the test method is 3 - see below)
Test Methods
• Random method - 1
1) Set gFontMethod to 1. (i.e. global gFontMethod := 1;)
2) Set gNumRandomFontTests to equal the number of random text records.
(i.e. global gNumRandomFontTests := 5;) For 5 random text records
3) Call DoText();
- The FontRecord generated will include a random Font, a random size,
and a random number of random styles.
• QuickLook method - 2
1) Set gFontMethod to 2. (i.e. global gFontMethod := 2;)
2) Call DoText();
- This will generate 1 FontRecord for each font with a random size and a random combination of styles.
• Waterfall method -3
1) Set gFontMethod to 3. (i.e. global gFontMethod := 3;)
2) Be sure the global gNextLineClearsFontSettings is set correctly (See above)
3) Call DoText();
- This will generate 1 FontRecord for each font with every size and combination of styles. For example, the first record may be {"Helvetica", '12', {'Bold'}}; and the second record might be {"Helvetica", '12', {'Bold', 'italic'}}
Performing Draw Operations
Using Palettes
This section describes the way to set up various structures to implement the draw libraries. Each application will have a unique set of tools contained within its own palettes. The following sections outline the requirements for using the Draw Libraries. Since these are unique for each application, the structure must be set up for each application and contained within an initialization routine for that application.
The Palette Structure
This section describes the setup required to use the palette section of the libraries.
First you must identify which type of palette is utilized. There are three main types of palettes that the Draw Libraries function with: (1) Palettes that are contained within the document window (kPalDocWind), (2) palettes that are contained within pop up menus (kPopUpPal), (3) and palettes that are contained within their own floating windows (kPalWind).
Once the type of palette is identified, a Palette Structure must be defined.
Note: Each palette type that is defined will be added to the gPaletteList.
Example of a generic Palette Structure:
global gPaletteList := {
{
{Specifiers}, # Different for each type of # palette
PaletteType, # Palette type
{numElemsWide,numElemsTall}, # Size of Tool matrix
{H,V} # Offset between tools
}
};
The kPalDocWind Palette
This section describes the setup required for using (kPalDocWind) palettes. Initially this type of palette was defined as palettes where a part of applications document window is reserved for tools. However, this palette definition has been extended to include any palette where it is necessary to define the coordinates for the palette. kPalDocWind palettes can be defined relative to the applications document window, a separate window, or in global coordinates. MacDraw Pro utilizes a kPalDocWind, which is relative to its document window, for its main drawing tools.
Note: Tools contained within palettes of this type must be the same size and the same distance apart.
kPalDocWind
Palette that is defined by coordinates.
Example of a Palette Structure with a single kPalDocWind palette defined:
global gPaletteList := {
{
{ 0, 21, 25, 228, (0)}, # Rect that contains tools/ # Relative indicator
kPalDocWind, # Palette type
{1, 12}, # Size of Tool matrix
{0, 17} # Offset between tools
}
};
The kPopUpPal Palette
This section describes the setup required for using a palette that is contained within a pop up menu or button (kPopUpPal). This type of palette in which the tools contained in the palette are not visible until the mouse is pressed at a particular point. MacDraw Pro utilizes this type of palette for colors in its color palette.
Note: Tools contained within palettes of this type must be the same size and the same distance apart.
kPopUpPal
Palette that is defined by coordinates.
Example of a Palette Structure with a single kPopUpPal palette defined:
This section describes the setup required for using a palette that is contained within its own window (kPalWind). MacDraw Pro's pattern palette (once 'pulled off') will be contained within its own window.
Note: Tools contained within palettes of this type must be the same size and the same distance apart.
kPalWind
Palette that is defined by coordinates.
Example of a Palette Structure with a single kPalWind palette defined:
Defining the palette structure is only the first step in using the Draw Libraries. By definition, each palette contains a number of tools. Each one of these tools may have a variety of behaviors. Some tools are used for drawing or selecting, others are used to enter text. Tools can be used to render objects of any shape and may allow patterns, line weights, and/or colors. The following section explains the setup required for using a variety of tools which may or may not be used with the palettes described above.
In order to make use of the Draw Libraries, tools structures for each tool in a given palette must be defined.
Tool Number
To access tools in a given palette the location of the tool within the matrix must be known. In order to do this, the tool number is used as a multiplier. It is important to number the tools correctly, so that the specified tool will be the expected one. Tools are numbered from left to right, top to bottom.
Example:
Palette Number
Palettes are numbered based on the order in which they appear in the global gPaletteList (or Palette Structure). All of the information concerning the actual selection of a tool from a palette is contained within the Palette Structure (detailed in the preceding section). Several routines within the Draw Libraries also need to access palette information <SetPattern, SetLine, SetColor>. In order to do so, they must index into the Global gPaletteList. Since palette information is specific to a particular palette, accessing the correct palette information is critical.
Once the global gPaletteList (or Palette Structure) is setup, global variables indicate the order in which palette information is specified within the Structure.
Set the following global variables as appropriate:
global kToolPaletteNum := 1;
global kColorPaletteNum := 2;
global kPatternPaletteNum := 3;
global kLinePaletteNum := 4;
The number assigned to each of the above palette globals has to correspond to its ordinal position within the list of palettes that you defined in global gPaletteList. (i.e. If you define the tool palette first in the global gPaletteList, the global kToolPaletteNum should be set to 1.) See the sample QuickLook in Appendix B.
Example:
Tool Name
The Tool Name field within a tool structure is used for logging purposes so that it is possible to differentiate between tools other than by number. Set this field to a string which is descriptive of the tools function.
Example:
Tool Type
The Tool Type field within a tool structure is one of the most important fields because it indicates how to use the tool once it has been selected. There are five types of tools that the Draw Libraries currently function with: kClick, kDrag, kMultiClick, and kMultiDrag, kDragClick.
0 (Zero) - Tool does not have a type, tool will be selected but not 'used'.
kClick - Tools that only require the user to move to the desired destination and click the mouse button, are considered kClick tools.
kDrag - Tools that require the user to press the mouse button move to a new location, and release the mouse, are considered kDrag tools.
kMultiClick - Tools that require the user to click to initiate the tool, move to any number of new locations, clicking at all corner points, and then double click to end (optional), are considered kMultiClick tools.
kMultiDrag - Tools that require the user to press the mouse, move to any number of new locations, and release the mouse button to end, are considered kMultiDrag tools.
kDragClick - Tools that require the user to press the mouse button, move to a new location and release the mouse, then click the mouse button are considered kDragClick tools.
Note: It is possible to specify whether a double click is necessary to end for any tool type.
Example:
DblClkFlag
The DblClkFlag field within a tool structure is used to indicate whether a double click is necessary to end usage of the tool. Setting the DblClkFlag (nonZero) indicates a double click is necessary, and when the last point of an object is drawn a double click will be issued by Virtual User. Setting the DblClkFlag to 0 (Zero) indicates that a double click is not necessary and one will not be issued by Virtual User.
Example:
Attributes
The Attributes field within a tool structure is one of the more complex fields mostly because the first element has several meanings. As mentioned briefly in the previous section (more to come in the following section) tools can be associated with Text, Patterns, Line weights and Colors. The flags within the Attributes field deal with a tool's ability to handle these attributes.
The first element indicates when/if to set specific attributes concerning an object that is to be created with the tool. It can be set to four valid settings: 0 (Zero) indicates the tool does not accept any attributes (no patterns, no line weights, and no colors), 1 indicates that at least 1 of the attributes is appropriate, and that the attribute(s) should be set prior to drawing the object (after selecting the tool), 2 indicates that at least 1 of the attributes is appropriate, and that the attribute(s) should be set after drawing the object (many objects stay selected after drawing), a text string indicates that the string should be typed after the object is drawn.
All of the flags (PatternFlag, LineWeightsFlag, ColorFlag) function in the same manner. If the flag is set (nonZero) then the attribute is appropriate for that tool.. If the flag is not set (Zero) than the attribute does not apply to the tool. It is important to realize that even if the indicator is set to a 'string', attributes can still apply. Also if the indicator is not set (Zero), all of the other flags will be ignored (therefore setting the Attributes Field to {0} is identical to setting it to {0,0,0,0}, or for that matter {1,0,0,0} and {2,0,0,0}).
Example:
Direct Coordinate Tools
Direct Coordinate tools are tools that require selection by coordinate instead of through a palette structure. This may be required if tools are not contained within a palette, or the tools do not fit the rule of being the same size and same distance apart. It is important to realize the only thing that changes is the method of selecting the tool. The tool retains all of its other characteristics. Since Direct Coordinate tools are not contained within a palette the structure element for Palette Number has a new meaning. This field is used for the coordinates for the point that when clicked will select the tool. These can be in global coordinates (default) or relative to the front document window by setting a relativeFlag.
Example:
Using Objects
As discussed briefly in the previous section, drawing tools can behave in different ways within the same application, not to mention other applications. A different set of attributes may apply for any given tool. The Object Structure is used to specify the attributes to set when drawing a given object.
The elements within an object structure include: (1) Tool Structure (see Tool Structure section), (2) Pointlist (3) PatStruct, (4) LineStruct, and (5) ColorStruct.
Example Object Structure:
MyObject := {
global LineTool, # Tool Structure
{{100,50}, {50,100}}, # Point List
{15, 2, 'Pattern'}, # PatStruct
{6, 3, 'Line'}, # LineStruct
{24, 4, 'Color'} # ColorStruct
};
In the example Object Structure above, the specified course of action is:
1) Select the Line Tool.
2) Select the 15th element in the Pattern palette (2nd palette struct in gPaletteList).
3) Select the 6th element in the Line palette (3rd palette struct in gPaletteList).
4) Select the 24th element in the Color palette (4rd palette struct in gPaletteList).
5) Move to the point (100, 50), relative to the top left corner of the document window, and pressMouse.
6) Move to point (50, 100) , relative to the top left corner of the document window, and releaseMouse.
Assumptions: All the Attributes flags in the tool structure are set (nonZero), and that the first Attributes flag (the Indicator flag) is set to 1, indicating that attributes should be set prior to drawing the object.
Tool Structures
See the Tool Structures section previously mentioned.
PointList
PointLists are lists of points (within the current document window) which will define the object to be drawn.
- Tools that are defined as type kClick require only one point.
- Tools that are defined as type kDrag require two points.
- All multi-point tools (kMultiClick and kMultiDrag) require at least two points. See gNumPoints in Appendix G.
Attribute Structures
PatStruct, LineStruct, ColorStruct
The last three elements of an object structure are attribute structures. Different attributes will apply to various tools. Attributes have been defined as Pattern, Line and Color, however these are merely labels and any attribute that is selected from a palette could be substituted. For instance, setting up a structure for a gradient palette and setting the gradient as an attribute instead of a color would be perfectly acceptable.
Example Attribute Structure:
Currently, the third element of an object structure, the PatStruct, is passed to SetPattern(), the fourth element of an object structure, LineStruct, is passed to SetLine(), and the fifth element of an object structure, ColorStruct, is passed to SetColor(). There are override capabilities, so that you are not limited to selecting attributes from a palette. See gSetPattern, gSetLine, gSetColor in Appendix G.
Example of Attribute Structures within an Object Structure :
Note: While an object structure can have defined Attribute Structures, if a tool's structure indicates that a particular attribute is not applicable (Attribute flag set to 0), the attribute will not be set (see Attributes section for details).
Example of a Tool Structure with an Attribute flag set to 0 :
Attribute Number
This is the number of the desired element within the specified palette ( see the Tool Number section for details concerning the numbering of tools).
Palette Number
This is the number of the palette containing the desired element. This should correspond to the order in which the palette structure appears in the global gPaletteList. ( see the Palette Number section for details concerning the numbering of palettes)
Descriptive String
The descriptive string is merely a way of reporting information that represents what has occurred. Stating that the fifth element of the second palette was selected does not adequately describe what took place, however stating that the fifth pattern was selected does.
Note: Setting an attribute structure within an object structure to zero indicates that the attribute is not to be set. Setting an attribute structure within an Object structure to 'Random' indicates that a random Attribute structure should be generated.
Example of a Object Structure with an Attribute flags set to 'Random', and 0 (Zero):
Using The Draw Libraries
In the previous section the requirements for setting up the various Draw Library structures were outlined. In the following section the details concerning actually using the Draw Libraries will be discussed. The Draw Libraries were designed to be as flexible as possible. They allow for several methods of automatically generating test cases, and a way that the script writer can specify tools and objects.
Calling the Draw Libraries
Along with the main routines that make up the Draw Libraries core functionality, several high level routines have been developed to assist the script writer in using the Draw Libraries.
nada DoDraw( pTestMethod, pSpecifier, pNumTimes )
DoDraw() is a highlevel task that calls the appropriate low-level tasks necessary to generate random objects based on the defined paletteStructs and toolStructs. If the global gDrawMethod is set it will override any parameter passed to DoDraw. All of our scripts call DoDraw() with no parameters so we can define which test method to use by setting the global gDrawMethod.
Examples:
• DoDraw(0); # Does nothing - DoDraw is turned OFF
• DoDraw(1); # Random objects for all tools defined in # global gToolList
• DoDraw(2); # Generates one totally random object
objectStruct DrawObject(objectStruct, specifier )
DrawObject() is the main routine in the Draw Libraries. It takes a complete ObjectStruct as a parameter and a specifier to indicate the window or rectangle to draw in.
Draw() takes six parameters, one for each element in an ObjectStruct and one to specify the window or rectangle to draw in. All of the parameters default to 'Random', which means that elements that are not specified will be generated randomly. Passing a 0 (Zero) for an element indicates that the attribute should not be set. The purpose of this task is to allow a script writer to pass in only the elements of an object that they want to specify. Draw will call DrawObject with a complete ObjectStruct (even though many of its elements may be equal to 'Random'). If a particular element is desired only that element needs to be passed in.
The SelectTool is specified so it will be used, a random Pointlist will be generated, no Pattern or Line will be set, and the 14th color will be selected (if the SelectTool allows for colors).
• Draw(, , , ,{14,3, 'Color'});
All elements in the above struct would be random except for the color attribute.
Note: If the random tool that is generated doesn't support the color attribute, this color struct will not be set.
• Draw();
All elements in the above struct will be random.
objectStruct GenerateObject( pTheObject )
GenerateObject() generates random objectStruct. It is possible to specify elements and have GenerateObject() generate random elements for those specified as 'Random'.
SetPattern() will set patterns based on the pThePattern parameter. If pThePattern = 'Random' a PatStruct will be generated before the pattern is actually set. If the pSelectPattern parameter = 0 (Zero) then the pattern will not actually be selected, however a random PatStruct will be generated and returned.
Examples:
• SetPattern('Random'); # Select random pattern (default)
• SetPattern(); # Same as above
• SetPattern(0); # Don't set any pattern ( no reason # to make call)
• SetPattern({15,2, 'Pattern'}); # Passing an actual patStruct
SetLine() will set line weights based on theLine parameter. If pTheLine = 'Random' a LineStruct will be generated before the line is actually set. If the gSelectLine parameter = 0 (Zero) then the line will not actually be selected, however a random LineStruct will be generated and returned. This routine is the default way of selecting line weights from palettes. In order for this to work a line paletteStruct needs to exist within the gPaletteList. The global variable kLinePaletteNum should then be set to the integer which represents the order in which the paletteStruct (for the line palette) exists within the gPaletteList.
Examples:
• SetLine('Random'); # Select random line weight (default)
• SetLine(); # Same as above
• SetLine(0); # Don't set any line Weight ( no reason # to make call)
• SetLine({12,3, 'Line'}); # Passing an actual LineStruct
SetColor() will set colors based on its parameter, pTheColor. If pTheColor = 'Random' a colorStruct will be generated before the color is actually set. If the pSelectColor parameter = 0 (Zero) then the color will not actually be selected, however a random colorStruct will be generated and returned. This routine is the default way of selecting Colors from palettes. In order for this to work a color paletteStruct needs to exist within the gPaletteList. The global variable kColorPaletteNum should then be set to the integer which represents the order in which the paletteStruct (for the color palette) exists within the gPaletteList.
Examples:
• SetColor('Random'); # Select random Color (default)
• SetColor(); # Same as above
• SetColor(0); # Don't set any Color ( no reason to
# make call)
• SetColor({15,4, 'Color'}); # Passing an actual colorStruct
SetTool() will set tools based on theTool parameter. If pTool = 'Random' a toolStruct will be generated before the tool is actually set. If the pSelectTool parameter = 0 (Zero) then the tool will not actually be selected, however a random toolStruct will be generated and returned. This routine is the default way of selecting Tools from palettes. In order for this to work a tool paletteStruct needs to exist within the gPaletteList. The global variable kColorPaletteNum should then be set to the integer which represents the order in which the paletteStruct (for the tool palette) exists within the gPaletteList. The global variable gToolList should be set to all of the available tools.
Examples:
• SetTool('Random'); # Select random Tool (default)
• SetTool(); # Same as above
• SetTool(0); # Don't set any Tool ( no reason to make # call)
• SetTool({4,1, 'Circle'}); # Passing an actual toolStruct
nada PalettePicker( pElemStruct, pObjectNumber )
PalettePicker() is a high level task that calls the appropriate tasks to actually select tools from various palettes. The parameter pElemStruct has three required elements {ElemNum, PalNum, ElemName}. If an elemStruct is passed in which contains more than these three elements, all others will be ignored. Normally, scriptors will not make calls directly to PalettePicker(). PalettePicker is called by all of the selection subroutines e.g. SetColor, SetPattern, SetLine, SetTool, DrawObject, etc.
Examples:
• PalettePicker(global LineTool);
# Selects the LineTool (if defined) Same as SetTool(global LineTool);
• PalettePicker({2,1,”Select”});
# Selects the second tool, from the 1st palette, named 'Select'. Assuming the 1st palette is set up correctly.
Test Case Tracking
Overview
SPEC S&L contains a collection of several tasks which support defining and tracking test case execution. This section describes the routines which support defining and tracking test cases.
In order to track test cases (TCS) we had to define several terms. A TCS is the smallest amount of functionality that a script writer may be interested in tracking. For example, A TCS could be defined as "Saving a Document". While there are many steps you would have to go through to save a document, you may not be interested in tracking every menu selection or keystroke.
The term suite is used to specify all of the test cases that were executed at a given time. Therefore, each of the SPEC S&L Standard QuickLook scripts can be considered a suite. The test cases that are executed as part of a suite do not have to be directly related, for example the Standard QuickLooks execute numerous Standard File test cases and numerous window related test cases. These groups of test cases are not related except for the fact that the applications the scripts were written for support both types of functionality.
How Test Case Tracking Works
All scripts must explictly make a call to indicate that a Suite is being started, this is done with a call to SuiteStart (see below for details). By making this call SuiteStart will store a number of variables about the state of the target machine so that an individual test case can be reproduced if necessary. For example, all of the software configuarable variables (VM, FileShare settings, etc.) will be outputted (see below for more details).
In order to track TCSs we have developed a mechanism by which you bracket your functionality tests with calls to TCSStart() and TCSEnd(). TCSStart() basically tells us what you are planning to do, and TCSEnd() tells us how successful your test was. It is important to understand that the script writer is responsible for determining how successfully the test completed. For more information about the different parameters used in TCSStart() and TCSEnd() see the headers inside the TCS.Lib. Appendix H contains a list of all the test cases in SPEC S&L.
A typical TCSSTart() call contains the following parameters:
(pTCSID, pTextDesc)
pTCSID is a list formed with the following information:
- Test Case Number
- Test Case Set*
- Test Case Type *(defaults to Compatibility)
- Owner. *(defaults to SPECS&L)
* If these defaults values do not meet your needs, you may pass your own values by reasigning the following constants in your script: kTCSetDefault, kTCTypeDefault, kTCOwnerDefault.
A typical TCSEnd() call contains the following parameters:
(pTCSID, pResultCode) There are several optional parameters available to provide additional imformation about the completion of the test case. See the header of TCSEnd() in the TCS.Lib.
A stack is used to handle TCS tracking. A balanced stack is critical to maintaining valid TCS results. In order to maintain a balanced stack it is important that every call to TCSStart() is offset with one, and only one call to TCSEnd(). So when writing new TCSs be especially careful that all of the branches within tasks will end up calling TCSEnd only once.
Example of a task that creates an unbalanced stack
While the example below looks fairly similar to the first example there is an important difference. Upon entering the task a call to TCSStart() is made. If the call to LaunchTwitch() is successful a call to TCSEnd() is made. But if the call to LaunchTwitch is unsuccessful no call to TCSEnd() is made, this will create an unbalanced stack and possibly report false results.
SuiteStart() is the first task that is called when running a script which contains test cases that need to be tracked. Calling this task will output many of the target's configuration variables.
Examples:
• SuiteStart("MyScript.vu");
# Indicates that the suite "MyScript.vu" is starting, will save off many of the targets configuration variables.
integer SuiteEnd( pCompletionCode )
When a suite that was started with SuiteStart() (see above) is completed a call to SuiteEnd() will output the amount ot time the suite took and the completion code for the script. There are four completion codes currently defined.
Completion Codes
1 := Suite Complete successfully
0 := Suite failed to complete successfully.
-1 := Suite was not available to run.
-2 := Target was lost during execution (possible crash) (see global gLaunchReqs for more details).
Examples:
• SuiteStart(0); # Indicates that the suite failed to
# complete successfully.
nada TCSStart( pTCSID, pTextDesc, pAppName )
In order to track specific test case using the SPEC S&L test case tracking mechanism, TCSStart should be called immediately prior to any actions that are a part of the functionality test. A unique TCS number must be assigned to each TCS that is being tracked, currently the SPEC team has a numbering scheme that can be made available upon request. The pTextDesc parameter is provided to make the output readable without requiring a database table to index the pTCSID. The pTextDesc should be set to a short string that describes the TCS. The pAppName should be passed in only if it is different than the global gAppTitle which is the default.
All calls to TCSStart() (see above) must be balanced with one (and only one) call to TCSEnd(). This is where success/failure is assigned to the TCS. It is possible to pass in a reason for failing, by using the pErrStr parameter. The pTCSVal and pTCSStr parameters are currently reserved for internal use by SPEC S&L Drawing and Font tasks.
Examples:
• TCSEnd({1,"MySet", "MyType", "MyGroup"},1); # Pass the top TCS on # the stack.
• TCSEnd({1,"MySet", "MyType", "MyGroup"},0, "There was no window to close");
# Fail the top TCS on the stack, because "There was no window to close".
Appendix A - QuickLook Definition
A QuickLook is a basic test of a third party application's compatibility with our system software. The following actions (not necessarily in the order tested) are standard in every QuickLook. For clarity, these actions are mapped to the high level Do tasks available in the SPEC S&L Libraries.
The following section describes the global variables that are used within SPEC S&L. It is important to understand that the majority of global variables used are actually constants. It is appropriate to set certain global variables prior to execution, however they will stay constant during runtime.
The reason that we use 'constants' instead of passing parmeters is that a great deal of the information contained within our data structure to 'model' the application is constant and used by many of the routines within the libraries, therefore passing this information by way of parameter would be redundant.
Each of the following sections describe global variables that affect various areas of functionality. The tasks containing the global variables are InitGlobals, InitDraw, InitFonts and InitRandomSeed. The section header will indicate the name of the task which initializes the global variables, and the library in which the global variables should be set and/or initialized. The actual global variable name will appear in bold, followed by a description of the functionality the global variable provides, possible values, whether or not it can be modified, the tasks that use the global variable, and the tasks that modify them. If there are no task names in the 'Modified by' field, you can assume that no library routines modify the global variable.
Initialized In The Initglobals Task
Task name - InitGlobals()
Location - Globals.Lib
Initialize - Must be initialized from within scripts prior to making any calls.
Miscellaneous
gAliasDirectory
Description :
Launching applications requires knowing where the application resides. SPEC S&L utilizes aliases to short cut this requirement. An alias is created for all of the applications that will have scripts executed against them. These aliases are palced in a directory, which in turn has an alias made for it. This alias is placed in the Apple Menu Items folder.
Possible values:
String
Can be Modified: Yes
Used by : Scripts use this directly to pass as a parameter to LaunchTwitch() when launching applications.
Modified by : Scripts
gAppTitle
Description:
This contains the name of the current application and should be explicitly defined by script upon launching applications to insure that the correct application is running. This is a part of the SPEC S&L application verification scheme(see task ApplicationVerification() for more details).
Possible values:
String
Can be Modified: Yes
Used by : Scrapbook(), DoWindow(), DoSetUpApp(), DoCloseApp(),
Modified by : MatchApplication() (Note: Both LaunchTwitch(), Quit()
modify it indirectly by way of a call to MatchApplication()).
gAppVerify
Description:
SPEC S&L has a background task which verifies that the application that is currently active is the intended application. The gAppVerify turns this verification scheme OFF(0) or ON(1).
Possible values:
Integer - Boolean ( 0 or 1 )
Can be Modified: Yes
Used by : LogStr()
Modified by: LaunchTwitch(), Quit(), and Scripts prior to or during runtime.
gBuildVers
Description:
This is contains the version of system software on the target machine.
Possible values:
String
Can be Modified: No
Used by : Scripts - to include the current version of the Operating
System in filenames generated during test runs.
Modified by : none
gCustomNewDocDialog
Description :
Define this as a window descriptor if you want to override the default window descriptor ([window o:1 s:dialog]) for dismissing any dialogs that appear right after selecting the New menu item from the File menu.. Used in DoSetUpApp().
Possible values:
Window descriptors
Can be Modified: Yes
Used by : DoSetUpApp()
Modified by : Scripts
gCustomOpeningDialog
Description :
Define this as a window descriptor if you want to override the default window descriptor ([window o:1 s:dialog]) for dismissing any dialogs that appear right after launching. Used in DoSetUpApp().
Possible values:
Window descriptors
Can be Modified: Yes
Used by : DoText()
Modified by : Scripts
gCustomRetrievedDoc
Description :
Define this as a window descriptor if you want to override the default window descriptor ([window g:true z:true t:?DocName]!) used in OpenFile ().
Possible values:
Window descriptors
Can be Modified: Yes
Used by : Scripts
Modified by : none
gDBLogging
Description:
Indicates whether or not to output database records
Possible values:
Boolean ( 0 or 1 )
Can be Modified: Yes
Used by : TCSStart(), TCSEnd(), SuiteStart(), SuiteEnd().
Modified by : Scripts - To suppress database output.
gDebugFlag
Description:
Indicates whether or not debugging values within the libraries will be printed.
Possible values:
Integer - Boolean ( 0 or 1 )
Can be Modified: Yes
Used by : DoDraw(), TCSEnd(), and the majorityof tasks within
Draw.Lib and Palette.Lib.
Modified by : Scripts - normally only when debugging.
gDisableAllLogging
Description:
This is used to suppress any logging from LogStr(). This can be reset at any point in a script where logging is undesireable.
Possible values:
Integer - Boolean ( 0 or 1 )
Can be Modified: Yes
Used by : LogStr(),
Modified by : DrawObject(), SelFromDocWind(), SelFromPalWind(),
SelFromCoord(), SelFromPopUp(), PageSize(), ToggleOrientation(), SFSelectPopupMenuItem(). (Note: All Library routines that modify this return it to its previous state prior to completion)
gIsSystem7
Description:
Indicates whether the current Operating System is System 7.0 or greater.
Possible values:
Integer - Boolean ( 0 or 1 )
Can be Modified: No
Used by : Twitcher(), Quit(), TwitchQuit(), LaunchTwitch(), OpenFile(),
ReplaceExist().
Modified by : none
gLastSavedFile
Description:
This contains the name of the last file that was saved by the task SaveAs().
Possible values:
String
Can be Modified: Only by SaveAs().
Used by :DoFiles(),CloseWindow(), Scripts.
Modified by : SaveAs().
gLogLevel
Description:
The output from many of the SPEC S&L routines are funneled thru a single task LogStr(). The gLogLevel is used to specify what type of output LogStr() should print. (see LogStr for more details)
Possible values:
Integer value between 0 and 5
Can be Modified: Yes
Used by : LogStr() in 'Output.Lib'.
Modified by : Scripts prior to or during runtime.
gLogStrCount
Description:
This is used by LogStr() to count the number of output lines it has processed.
Possible values:
Integer
Can be Modified: Only by LogStr().
Used by :LogStr().
Modified by : LogStr().
gMachineName
Description :
Name of the target machine.
Possible values:
String
Can be Modified: No
Used by : TCSEnd(), SuiteEnd(), SuiteStart()
Modified by : none
gPatchLaunchTwitch
Description:
Indicates whether or not the standard launching mechanism in SPEC S&L will be used.
Possible values:
Boolean - 0 (Use Standard Launching Mechanism) or 1 (Use custom Launching Mechanism)
Can be Modified: Yes
Used by : LaunchTwitch()
Modified by : Scripts
gPrevAppTitle
Description:
This contains the name of the last application that was running, and should be utilized when twitching back to a previous application is required. e.g. Scrapbook tests require twitching back to the previous application.
Possible values:
String
Can be Modified: Only LaunchTwitch().
Used by : Scrapbook(),
Modified by : LaunchTwitch().
gPrintTest - Not currently supported
Description :
Flag which indicates whether or not print testing will occur.
Possible values:
Integer - Boolean ( 0 or 1 )
Used by :
Modified by : Scripts
gSFPUTLocation
Description :
SF_PutLocation contains the path to the directory in which files will be saved by the task SaveAs(). If the list is empty files will be saved in the default directory. Example: SF_PUTLocation := {"myDisk"};
Possible values:
List
Can be Modified: Yes
Used by : SaveAs()
Modified by : Scripts
gSFOriginalPath
Description:
This contains the path for Standard File before navigation occurs. It is updated every time navigation occurs in Standard File from SaveAs() or OpenFile(). It can be used as a mechanism to navigate back to your original directory.
Possible values:
List
Can be Modified: Normally only by the library routines listed below.
Used by : Could be used by scripts.
Modified by : SFNavigate(),
gSpectest
Description:
Indicates whether or not any special tests designated by calls to DoSpecialTest() will be completed. Note: DoSetUpApp() and DoCloseApp() are the only library tasks which make calls to DoSpecialTest().
Possible values:
Integer - Boolean ( 0 or 1 )
Can be Modified: Yes
Used by : Scripts
Modified by : Scripts
gTargetCheck
Description:
Most output is funneled through a single task LogStr(). LogStr() will append the name of the target application to any output if the gTargetCheck is true.
Possible values:
Integer - Boolean ( 0 or 1 )
Can be Modified: Yes
Used by : LogStr()
Modified by : Scripts prior to or during runtime.
gTextStr
Description :
A text string used when typing in the Font and Draw libraries.
Possible values:
String
Can be Modified: Yes
Used by : CheckSetup(), DoText(), Scripts
Modified by : InitGlobals(), Scripts
gDoWindowList
Description :
This is a list of flags indicating which window tests are appropriate for a given aplication. By setting each element to 1 or 0 the script writer can specify whether a certain type of window testing will be performed from the task DoWindows() for a given application. Redefine this in your application script if your application cannot do all of the window tests specified below, e.g. if VU can't recognize the scroll bars, in your app script define global gDoWindowList := {1,0,1,1};. (See example in Canvas.vu)
First element - Sizing.
Second element - Scrolling.
Third element - Dragging.
Fourth element - Zooming.
Possible values:
List of Boolean integers( 0 or 1 )
Can be Modified: Yes
Used by : DoWindows(), TestWindow()
Modified by : Scripts
Task Reference (Related to Globals)
gExitVU
Description :
This task makes the built in VU task Exit. The purpose of defining this as a task is so we can use a task reference to this task- gExitVU. This way we can default our Exception Handling task to call the task reference gExitVU and thus exit. If others do not want to exit, they can redefine the task reference to what ever task they prefer.
Possible values:
Task reference
Can be Modified: Yes
Used by : Globals.Lib
Modified by : Must be defined in Custom.Lib for overwriting it
Launching/Quitting
gBackgroundQuit
Description :
Flag indicating whether or not to use the BackgroundQuit mechanism. The background quit mechanism means that the task Quit() will not actually quit the current application, rather it will close all open windows. When the task launchTwitch() attempts to launch a new application a dialog will appear prompting background quitting to free enough memory to launch. If gBackgroundQuit is enabled the “OK” button will be selected, otherwise, the “Cancel” button will be selected.
Possible values:
Integer - Boolean ( 0 or 1 )
Can be Modified: Yes
Used by : Quit(), QuitBackgroundApps(), TwitchQuit()
Modified by : Scrapbook(), LaunchFillMemApp, Scripts
gFillMemory
Description :
Flag indicating whether or not to use the FillMemory mechanism. The FillMemory mechanism means that the task Launchtwitch() will launch another application <global gFillMemApp> (see gFillMemApp below) after it has successfully launched the desired application. Quit() will also quit the <gFillMemApp> when quitting.
Possible values:
Integer - Boolean ( 0 or 1 )
Can be Modified: Yes
Used by : Quit(), LaunchTwitch()
Modified by : Scrapbook(), TwitchQuit(), LaunchFillMemApp(), Scripts
gFillMemApp
Description :
The name of the application that is to be used to fill memory in the FillMemory mechanism (see gFillMemory above). Set this application's memory allocation high enough to use up all additional memory on the target machines, place it's alias in the Apple menu or in the alias directory.
Possible values:
Integer - Boolean ( 0 or 1 )
Can be Modified: Yes
Used by : Quit(), LaunchFillMemApp()
Modified by : Scripts
gForceQuit
Description :
Flag indicating whether or not to use the ForceQuit mechanism. The ForceQuit mechanism means that the task Quit() will not quit the current application. It won't do anything. When the task launchTwitch() attempts to launch a new application, if a dialog appears stating that there is not enough memory to launch, Launchtwitch() will twitch to and quit applications until it can successfully launch the desired applicaton.
Possible values:
Integer - Boolean ( 0 or 1 )
Can be Modified: Yes
Used by : Quit(), TwitchQuit(), LaunchAssist()
Modified by : Scrapbook(), LaunchFillMemApp(), TwitchQuit(), Scripts
Scrapbook Constants
The following constants are provided so that scripts can have access to different types of data without relying on hardcoding the position in which they appear in the Scrapbook into each script. It is appropriate to set these global variables prior to execution so that they reflect the appropriate positions, they are static at runtime.
kScrapTEXT := 1; # Test is 1st position
kScrapPICT := 2; # PICT is 2nd position
Controlling The Test Level
Control to the test level is provided by the script parameter “ScriptLevel”,
Script MacDrawPro (ScriptLevel := -1)
which can be defined as a list.
{ level, { {'method', method level, times to be performed } },..
The first element of the list controls the amount or level of testing to be performed for 'Draw', 'Window', 'Font' and 'AppTestLevel'. The possible values that each method can have are:
-1 - undefined
0 - no test to perform, unless a custom test method is specified
1 - least amount of testing
2 - medium amount of testing
3 - most amount of tetsing
The second element of the list is optional and can be defined as a list of lists, specifiying one or more methods to test in a customized manner. You can specify not only the method and the level for that method, but also the number of times to perform that method.
This convention can be illustrated with the following examples:
Script MacDrawPro ( {3} )
# perform the most amount of testing for all four methods
Script MacDrawPro ( {0, { { {'Draw', {3}}} })
# Custom control, only perform the Draw method test at the most level.
Script MacDrawPro ({ 2, { { {'Draw', {3, 3}}} } )
# Custom control, perform medium test for 'Window', 'Font. In addition, perform the Draw method at the most level, three times.
# Custom control, perform most test. In addition, perform Font method at the most level, five times. And the Window method at medium level, four times.
Test Method Constants
The following set of constants allow a script writer to set the behavior of several of the high level test methods e.g. DoDraw(), DoText(). If a parameter has been passed into any of these tasks, the constants will not override the parameter. The SPEC S&L scripts do not pass parameters to these tasks, but utilize these constants when determining the test method.
gDrawLevel
Can be defined as a list
Possible values:
0 - indicates that DoDraw() will not perform any draw testing.
1 -indicates that DoDraw() will create a random object for one of the tools defined within gToolList within a particular script (see section titled Using the Draw Libraries for more details) .
2 -indicates that DoDraw() will create a random object for all of the tools defined within gToolList within a particular script (see section titled Using the Draw Libraries for more details) .
gWindowLevel
Possible values:
0 - indicates that DoWindow() will not perform any window tests.
1 -indicates that DoWindow() will perform a limited set of window tests.
2 -indicates that DoWindow() will perform a complete set of window tests.
gFontLevel
Possible values:
0 - indicates that DoText() will not perform any font tests.
1 -indicates that DoText() will perform a random set of font tests one of the fonts defined in gFontList (see section Exercising Fonts).
2 -indicates that DoText() will perform a random set of font tests for each font defined in gFontList (see section Exercising Fonts).
3 -indicates that DoText() will perform a waterfall set of font test for each font defined in gFontLists (see section Exercising Fonts).
gNumRandomFontTests := 1;
Possible values:
integer - indicates number of random font tests that will be generated from gFontMethod := 3; (see above).
Initialized In The Initdraw Task
Task name - InitDraw()
Location - Draw.Lib
Initialize - Must be initialized from within scripts prior to making any calls.
Misc. Draw Related Script Global variables
The following global variables(constants) are default values and if an application needs to override them it should be done from within the script.
gBoundingRect
Description :
Rectangle in which points will be generated for random drawing. If this is not defined the rectangle of the document window (less the gWindowInset) will be used.
Possible values:
List
Can be Modified: Yes
Used by : MakePointList()
Modified by : DoWPTools(), Scripts
gDrawObject
Description :
We generate TCS records for many of the actions that occur when calling the SPEC S&L libraries. Since multiple TCS's are often generated when performing a single action it is important to tie multiple TCS records together. gDrawObject is used to tie together the TCS records that are generated when drawing an object using the Draw Libraries. This is initialized in InitControlGlobals() and incremented in DrawObject() in 'Draw.Lib'. Script writers should not change this value explicitly.
Possible values:
Integer
Can be Modified: Only by DrawObject()
Used by : SetAttributes()
Modified by : DrawObject()
gLineWeights
Description :
If an application utilizes menus instead of a palette to set line weights, this list should be defined as the names of the menuItems which are line weights. This list will only be accessed if gSetLine is set to Task SetLineMenuItems() (see gSetLine above). It should be redefined by individual scripts if necessary, not altered in InitControlGlobals(). Note: The task SetLineMenuItems() has been provided in the libraries since it is a common task override to SetLine().
Possible values:
List
Can be Modified: Yes
Used by : SetLineMenuItems()
Modified by : Scripts
gNumPoints
Description :
Many of the tools available, defined in the Draw Libraries require numerous points to generate a given object. This indicates the number of points to generate for any multipoint tool.
Possible values:
Integer greater than 2.
Can be Modified: Yes
Used by : SetPointList()
Modified by : Scripts
gScreenInset
Description :
Inset into the screen region of the main monitor. Applications will often create regions which are not accessible, e.g. it is not possible to drag a window where the menubar is drawn.
Possible values: List
Can be Modified: Yes
Used by :TestWindow(), WindowFunction(), DragWindow(), SizeWindow()
Modified by : Scripts
gVoidRect
Description :
Rectangle in which points will not be generated for random drawing. If this is not points will be generated in this rectangle within the applications window. This rect should be defined in coordinates that are relative to the top left corner of the applications document window.
Possible values:
List
Can be Modified: Yes
Used by : MakePointList()
Modified by : Scripts
gWindowInset
Description :
Inset into the content region of the document window. It is not always possible to have access to all portions of a document window. For example, it is not possible to draw in the scroll bar section of a document window.
Possible values: List
Can be Modified: Yes
Used by : MakePointList() .
Modified by : Scripts
Task References (Draw Related)
The follow set of task references define which default library tasks are used to perform certain functionality. If there is a need to override any of these task references, all overriding should occur in the script where overriding is necessay. Many of the SPEC S&L scripts depend upon the default settings to execute properly. Task references are not supported in Virtual User 1.x, thus depend upon Virtual User 2.0x.
gSetColor := Task SetColor;
Description:
Indicates the task that will be called to set colors when drawing objects using the Draw.Libs.
Possible values:
Task reference
Can be Modified: Yes
Used by : SetAttributes().
Modified by : Scripts
gSetLine := Task SetLine;
Description:
Indicates the task that will be called to set line weights when drawing objects using the Draw.Libs.
Possible values:
Task reference
Can be Modified: Yes
Used by : SetAttributes().
Modified by : Scripts
gSetPattern := Task SetPattern;
Description:
Indicates the task that will be called to set patterns when drawing objects using the Draw.Libs.
Possible values:
Task reference
Can be Modified: Yes
Used by : SetAttributes().
Modified by : Scripts
Tool Type Constants
The following set of constants is used to provide a unique label for different types of tools. These global variables are not configurable, and should not be altered.
kClick := 1;
kDrag := 2;
kDragClick := 3;
kMultiDrag := 4;
kMultiClick := 5;
kMultiClickDrag := 6;
Palette Type Constants
The following set of constants is used to provide a unique label for different types of palettes. These global variables are not configurable, and should not be altered.
kPalDocWind := 1;
kPalWind := 2;
kPullOffPal := 3;
kPopUpPal := 4;
kScrollPal := 5;
Initialized In The Initfonts Task
Task name - InitFonts()
Location - Font.Lib
Initialize- - Must be initialized from within scripts prior to making any calls.
Misc. Font Related Script Global Variables
The following global variables(constants) are default values and if an application needs to override them it should be done from within the script.
gFontObject
Description :
We generate TCS records for many of the actions that occur when calling the SPEC S&L libraries. Since multiple TCS records are often generated when performing a single action it is important to tie multiple TCS's together. gFontObject is used to tie together the TCS records that are generated when exercising Fonts, an object using the Font Libraries. This is initialized in InitControlGlobals() and incremented in: WaterFallFontTest() in 'Font.Lib', and DoText() in 'DoTasks.Lib'. Script writers should not change this value explicitly.
Possible values:
Integer
Can be Modified: Only by the tasks specified below.
Used by : WaterFallFontTest(), DoText()
Modified by : WaterFallFontTest(), DoText()
gFontList
Description :
List containing the names of font menu items which will be used by DoText when exercising fonts.
Possible values:
List of strings.
Can be Modified: Yes
Used by : DoText(), RandomFontRecords(), WaterfallTest(), QuickLookTextTest() not currently supported.
Modified by : InitFonts(), Scripts
gFontSizeList
Description :
List containing the names of font size menu items which will be used by DoText when exercising fonts.
Possible values:
List of strings.
Can be Modified: Yes
Used by : SetSize(), RandomFontRecords(), WaterfallTest(),
QuickLookTextTest() not currently supported.
Modified by : InitFonts(), Scripts
gFontStyleList
Description :
List containing the names of font style menu items which will be used by DoText when exercising fonts.
Possible values:
List of strings.
Can be Modified: Yes
Used by : RandomFontRecords(), WaterfallTest(),
Modified by : InitFonts(), Scripts
gNextLineMethod
Description :
Method which will place the insertion point so that it is ready for a new line of text.
Possible values:
Integer or List
1 - ReturnKey,
2 - EnterKey
3 - DownArrow Key
4 - TabKey
{} - Move/Click
{'Untitled'} - Move relative to the window titled 'Untitled' /Click
Can be Modified: Yes
Used by : NextLine()
Modified by : InitFonts(), Scripts
gNextLineClearsFontSettings
Description :
Flag indicating whether moving to the next line clears all currently selected font sizes and styles and resets back to a default value.
Possible values:
Integer - Boolean ( 0 or 1 )
Can be Modified: Yes
Used by : WaterfallTest()
Modified by : InitFonts(), Scripts
gPlainStyle
Description :
Name of the Plain style menu item or name of the menu item which removes all font styles.
Possible values:
String
Can be Modified: Yes
Used by : WaterfallTest(), SetFontParams()
Modified by : InitFonts(), Scripts
Task References (Font Related)
The following set of task references define which default library tasks are used to perform certain functionality. If there is a need to override any of these task references, all overriding should occur in the script where overriding is necessay. Many of the SPEC S&L scripts depend upon the default settings to execute properly. Task references are not supported in Virtual User 1.x, thus depend upon Virtual User 2.0x.
gSetFont := Task SetFont;
Description:
Indicates the task that will be called to set fonts when exercising fonts using Font.Lib.
Possible values:
Task reference
Can be Modified: Yes
Used by : SetFontParams().
Modified by : Scripts
gSetSize := Task SetSize;
Description:
Indicates the task that will be called to set font sizes when exercising fonts using Font.Lib.
Possible values:
Task reference
Can be Modified: Yes
Used by : SetFontParams().
Modified by : Scripts
gSetStyle := Task SetStyle;
Description:
Indicates the task that will be called to set font styles when exercising fonts using Font.Lib.
Possible values:
Task reference
Can be Modified: Yes
Used by : SetFontParams().
Modified by : Scripts
gNextLine := Task NextLine;
Description:
Indicates the task that will be called to move to the next line to enter additional lines of text when exercising fonts using Font.Lib.
Possible values:
Task reference
Can be Modified: Yes
Used by : ReportSelectedMenuItems().
Modified by : Scripts
Initialized In The Initrandomseed Task
Task name - InitRandomSeed()
Location - Globals.Lib
Initialize - Automatically initialized by InitGlobals().
gSeedValue
Description :
This is the value which will be seeded to the Virtual User built in task randomSeed(). It is used to generate all random numbers during runtime. Tests can be produced which contain randomness. If it is necessary to reproduce these tests it is possible by seeding the RandomSeed with the same integer. If gSeedValue is set to 0 a random number will be generated and output for possible use when reseeding.
Possible values:
Integer
0 := Generate a random seed.
Any other integer := Use the value as actual random seed.
Can be Modified: Yes
Used by : InitRandomSeed(), SuiteStart()
Modified by : InitRandomSeed(), Scripts
gSeedZero
Description :
Flag indicating whether or not the gRandomSeed (seen above) should be set to zero. Setting this global to true indicates that the gSeedValue will equal zero.
Possible values:
Integer - Boolean ( 0 or 1 )
Can be Modified: Yes
Used by : InitRandomSeed()
Modified by : Scripts
Undefined Task References - Hooks
The following series of global variables are undefined tasks references. They have been provided as a hook into the libraries so that script writers have the flexibility to call custom tasks which may be required when performing certain functions.
A task reference is similar to a Proc Pointer in other programming languages. An undefined task reference is similar to a call back routine in that it will only be called if a script writer defines it. The following example illustrates the way in which undefined task references are used:
Task ScrapbookTest(ScrapItem)
begin
if (global gScrapbookSetup) # Hook to do anything prior to
call (gScrapbookSetUp); # Scrapbook call
Scrapbook(ScrapItem); # Call to Scarpbook
end;
If a script writer isn't interested in doing any setup prior to the call to the Scrapbook() task, defining the gScrapbookSetup hook would not be required since gScrapBookSet is undefined by default. However, if a script writer wanted to make use of this task reference the global gScrapbookSetUp should be defined as the desired task prior to making the call to the ScrapbookTest() task. For example:
global gScrapbookSetUp := Task myScrapSetup;
Example Mechanism for Using Task References - Hooks
Often times when using task reference hooks provided by SPEC S&L
you will need parameters which you may or may not have access to.
The following example is one method of using the task reference hooks
which gets around this problem of not having access to the parameters.
For instance, you have a task, TaskA. TaskA has a undefined task reference
(also refered to as a hook), Hook1, which you are interested in using.
However, you need to have access to some of TaskA's parameters in Hook1.
In order to do this write a new task, TaskB, which calls TaskA. Before calling
TaskA, TaskB defines a global variable equal to any/all of the parameters you are
interested in. Now Hook1 has access to TaskA a parameters by accessing this
global variable. Instead of calling TaskA you should call TaskB so Hook1 will
function as expected.
The example that follows uses the task OpenFile() which contains the undefined task reference 'gOpenFileHook1'.
gClearDoText a hook in DoText() for any cleanup that needs to happen after text tests end. DoText()
gCustomScrapPict to replace the default call to Scrapbook (global kScrapPICT) in DoSetupApp () with your own set of calls. DoSetUpApp()
gCustomScrapText to replace the default call to Scrapbook (global kScrapTEXT) in DoSetupApp () with your own set of calls.
DoSetUpApp()
gDismissSFPut a hook in SaveAs () at the end of the SaveAs() tasks for various dialogs.
DoText()
gDoCloseAppHook1to do anything before any actions are taken in DoCloseApp() DoCloseApp()
gDoCloseAppHook2hook to do anything after printing DoCloseApp()
gDoCloseAppHook3hook to do anything after quiting the app DoCloseApp()
gDoSetupAppHook1hook to do anything before DoSeupApp() actions are completed DoSetupApp()
gDoSetupAppHook2replaces DoSpecialTest(1) with 1 as parameter. Hook to do anything after dismissing opening diaolog. DoSetupApp()
gLaunchTwitchHook1hook to do anything prior to Preflight LaunchTwitch()
gLaunchTwitchHook2hook to do anything prior to any type of launching LaunchTwitch()
gLaunchTwitchHook3hook to do anything prior to launching by type selecting LaunchTwitch()
gLaunchTwitchHook4hook to do anything priot to returning LaunchTwitch()
gLogStrHookhook to do anything after logging LogStr()
gModifyDocument to do something other than the default for modifying a document (which is typing a string of text), e.g. if you need to paste from the scrapbook in order to modify your document. Requires a return value to indicate success or failure. (See example in the Canvas.vu sample script.)
ModifyDocument()
gOpenFileHook1before typing the name of the document to be opened.
OpenFile()
gPatchLaunchTwitchhook to substitute SPEC S&L's launching with another method LauchTwitch()
Hook NamePurpose Used by
gPreSelectButtonHook a hook in SelectButton() before selecting a button.
SelectButton()
gPreSelectMenuItemHook a hook in SelectMenuItem() before selecting a menu item.
SelectMenuItem()
gPostSelectMenuItemHook a hook in SelectMenuItem() after selecting a menu item.
SelectMenuItem()
gPreKeyEqHook a hook in KeyEq() before selecting a key equivalent.
KeyEq()
gPreMoveMouseHook a hook in MoveMouse() before moving the mouse.
MoveMouse()
gPreSpecialKeyHook a hook in SpecialKey() before selecting a special key.
SaveAs()
gReportSelectedMenuItems to replace the default calls in ReportSelectedMenuItems() with your own set of calls.
DoText(), WaterfallFontTest()
gSetupDoDraw to do something prior to performing tests using DoDraw().
DoDraw()
gSetUpForSaveDoc to do additional set up before saving a document, e.g. closing a window.
DoSetUpApp()
gSetupDoText to do something prior to performing tests using DoText().
DoText()
gSaveAsHook1 a hook in SaveAs(). For example, saving files in other formats.
SaveAs()
gSaveAsHook2a hook in SaveAs(). For example, after saving a document.
SaveAs()
gSaveAsHook3a hook in SaveAs(). For example, to dismiss additional dialogs after a save, such as the summary-info dialog in Microsoft Word v.5.0.
SaveAs()
gSuiteFooterHookused to add information to the suite footer SuiteEnd()
gTCSStartHook1hook to do anything before TCSStart si called TCSStart()
gTypeStrOverRideused to manipulate strings that contain two-byte characters TypeStr()
Appendix H - Test Cases in SPEC S&LOwner /
TCType TCSet : TC# Desc Task Library
SPECS&L
Compatibility Launch : 1 Launch '{ItemName}' via Apple Menu LaunchByAppleMenu LaunchQuit.Lib
SPECS&L
Compatibility Launch : 2 Launch '{AppName}' via Type Select LaunchByTypeSelect LaunchQuit.Lib
SPECS&L
Compatibility Launch : 3 Launch or twitch to '{AppName}' LaunchTwitch LaunchQuit.Lib
SPECS&L
Compatibility Launch : 4 Twitch from {global gapptitle} to {AppName} via process list Twitcher LaunchQuit.Lib
SPECS&L
Compatibility Quit : 1 Selected the 'Quit' menuitem Quit LaunchQuit.Lib
1 to 999 PalettePicker -> xyy (x indicates palette number - yy indicates tool number) PalettePicker Palette.Lib
SPECS&L
Compatibility ToolPalette :
1 to 999 SelectFromCoord -> the TC# indicates tool number SelFromCoord Palette.Lib
Appendix I - Utility Tools
Many tools have been developed that aid developing automated Virtual User scripts. This section details the tools that seem to be most useful for us.
MouseTrap
An application which displays mouse coordinates. It displays global mouse coordinates, mouse coordinates relative to the top left corner of the front window, and mouse coordinates relative to the last click. This tool is very handy when setting up data structures for Draw tools
vuCollect
Collects, formats and displays VU descriptor information. It's very useful to capture menu names, window names and to determine what VU can recognize.
MiniLauncher
An application that launches other applications, or files. It also allows for printing files from the Finder.
OnTarget
VU external tool which provides services that extend the feature set available from Virtual User. Services include:
Service "BitDepth"() return 'integer';
Service "MonitorCount"() return 'integer';
Service "ColorCheck"( 'integer' ) return 'integer';
Service "SetColor"( 'integer' ) return 'integer';
Service "CacheTest"() return 'integer';
Service "FileShare"() return 'integer';
Service "DiskSpace"() return 'list';
Service "GDelete"('integer', 'string');
Service "vers"('string', 'string') return 'list';
To access services use the OnTarget.vu VU library. For additional information see OnTarget documentation.
Notes
Ç ◊# ˇ ˇˇˇˇ # ◊ ° ñ † ó ° ñ † ó ° ñ † ó ° ñ † ó ° ñ † ó ° ñ † ó ° ñ † ó ° ñ † ó ° ñ † ó ° ñ † ó ° ñ † ó ° ñ